Related Issue

Fixes #314

This PR reintroduces the feature originally attempted in PR #529, which was closed after becoming stale. The goal of the issue is to decouple two behaviors that are currently tied together in the split_individuals argument of save_poses.to_dlc_file().

Background

Currently, the split_individuals argument controls two independent behaviors simultaneously:

1. Whether individuals are written to separate files

2. Which DeepLabCut dataframe format is used

• Single-animal format (< DLC 2.0)

• Multi-animal format (>= DLC 2.0)

Because these two behaviors are coupled, users cannot independently control:

• the file splitting strategy
• the DeepLabCut dataframe format

For example, it is currently not possible to:

save one file per individual while still using the modern multi-animal DLC dataframe format.

Several workflows (including compatibility with tools expecting the DLC >=2.0 format) benefit from being able to control these behaviors independently.

Proposed Solution

This PR introduces a new argument to explicitly control the DLC dataframe format:

dlc_df_format: Literal["single-animal", "multi-animal"] = "multi-animal"

Updated function signature:

def to_dlc_file(
ds: xarray.Dataset,
file_path: str | Path,
split_individuals: bool = False,
dlc_df_format: Literal["single-animal", "multi-animal"] = "multi-animal",

This separates the two previously coupled behaviors:

Default Behavior

The default behavior remains fully backward compatible:

split_individuals = False

dlc_df_format = "multi-animal"

This produces a single output file using the modern DLC >=2.0 dataframe format, which is general enough to support both single- and multi-animal datasets.

Implementation Details

The implementation focuses on a minimal and clean change set:

1. Introduced the new dlc_df_format parameter.

2.Updated the internal dataframe generation logic in to_dlc_style_df.

3. Ensured correct handling of both:

• single-individual datasets
• multi-individual datasets

4.Preserved the existing dataset validation behavior.

5. Avoided introducing unrelated changes that were present in the previous PR (Splitting_Individuals_and_DLC_Format  #529).

Tests

Relevant tests in tests/test_unit/test_save_poses.py were updated to reflect the new parameter and to verify:

• correct dataframe format generation
• correct file splitting behavior
• compatibility with both dataset types

Full test suite results:

1027 passed, 4 deselected, 2 xfailed

Coverage remains unchanged:

87% total coverage

Notes

• This PR intentionally keeps the scope minimal to focus only on the requested feature.

• It supersedes the previous attempt in PR Splitting_Individuals_and_DLC_Format  #529 while preserving the original design idea.

• No breaking API changes were introduced; the new parameter has a sensible default.